Using triggers

Use triggers and actions to create interactions based on user input. A trigger defines a condition and an action defines what the trigger does when that condition is met. For example, to execute a JavaScript script when a node is attached to the scene graph, add the On Attached trigger to that node and add the Execute Script action to that trigger.

Kanzi Studio has a range of actions which you can add to a trigger. For example, you can add an action to print to the Log window (Write Log), set a property to a certain value (Set Property), navigate to a Page node (Navigate to Page), or change application theme (Activate Theme).

Trigger messages

When a trigger intercepts a message that originates from an action you can set what the trigger does with the message. You can:

With a trigger you can intercept a message either at the node where the message originates, or in a trigger in any of its ancestor or descendant nodes. You can intercept many different message types in the same node. When a message travels up the project tree, the message bubbles. When a message travels down the project tree, the message tunnels. You can set in the action that creates the message whether the message bubbles, tunnels, or both bubbles and tunnels.

For example, if the action creates a bubbling message, after an action generates a message, the message bubbles from the node that receives the input to its parent node, then to the parent's parent, and so on until a trigger intercepts the message. If the trigger also handles the message, the message stops bubbling (traveling up the project tree). If none of the ancestors handle the message, the message travels all the way to the root node of the project.

By default all triggers handle their own messages. You can control the handling of trigger messages by setting the Set Message Handled property in the Trigger Settings.

Getting started

To get started with triggers, see:

For a list of all the triggers you can use in Kanzi Studio, see Triggers reference.

For a list of all the actions you can add to a trigger in Kanzi Studio, see Actions reference.

Adding a trigger

The most common place to add a triggers is in the node that uses the trigger, but you can add a trigger to any node.

To add a trigger:

  1. In the Project create or select a node to which you want to add a trigger.
    For example, create a Button 2D node. When you create the Button 2D node it already has a Button: Click trigger.
  2. In the Node Components > Triggers section right-click, select Add Trigger, and select a trigger that intercepts the type of message you want to intercept.
    For example, add an On Attached trigger. The On Attached trigger is set off when Kanzi attaches the node to the scene graph.
  3. In the Node Components > Triggers section click the Add dropdown menu for the trigger you added in the previous step and select an action.
    For example, select the Write Log action and enter a message you want to write to the Log window when the trigger is set off. The Write Log action is useful when you want to verify that the node received the input.
    You can add any number of actions. Kanzi carries out the actions in the order beginning from the first action.

    When Kanzi attaches the node, it prints the message you entered as the value of the Log Message property to the Log window. To open the Log window, in the main menu select Window > Log.
  4. (Optional) If you want the trigger to be set off only under specific conditions, in the Node Components > Triggers section under the trigger for which you want to set a condition, click Trigger Settings, in the Trigger Settings Editor click Add condition, and define the condition. See Adding conditions to a trigger.

Setting the handling of trigger messages

When a trigger handles a message it consumes it so that the message stops at the trigger that handles it and no other node can intercept it. See Creating custom messages in Kanzi Studio.

To set the handling of trigger messages:

  1. In the Node Components > Triggers section under the trigger for which you want to set message handling, click Trigger Settings.
  2. In the Trigger Settings Editor set:

Adding conditions to a trigger

Trigger conditions enable you to set which conditions must be met for the trigger to set off. For example, you can define conditions to set off a trigger when the user navigates to a specific Page node, enable the user to click a button only when that button is visible, or enable the user to scroll a scroll view only when a specific Page node is active.

You can add conditions to triggers in the Trigger Condition Editor. You create a condition by comparing a value you define in the Value A section to the value you define in the Value B section using an operator you set with the Operator property.

You can create conditions to set off a trigger when:

Creating a condition using a value from a property

You can define a trigger condition to set off a trigger when a property you select gets a value you set in that condition. For example, you can create a condition which allows the user to scroll a Scroll View node only when a specific Page node is active.

To create a condition using a value from a property:

  1. In the Project select or create a node with a trigger to which you want to add a condition and in the Node Components for the trigger click Trigger Settings. See Adding a trigger.
    The Trigger Settings Editor opens.
    For example, create a Scroll View 2D node with a Scrolled trigger and in the Node Components click Trigger Settings for that trigger. See Using the Scroll View nodes.
  2. In the Trigger Settings Editor click Add condition.
    The Trigger Condition Editor opens.
  3. In the Trigger Condition Editor set the condition that must be met for the trigger to set off. You create a condition by comparing a value you define in the Value A section to the value you define in the Value B section using an operator you set with the Operator property.
    In the Trigger Condition Editor set:Click Save.
    Here you created a condition which sets off a trigger when the user navigates to the Page node Media.

Creating a condition using a value from a message

You can define a trigger condition to set off a trigger when a message you select gets a value you set in that condition. You can use values from messages of these triggers:

For example, you can set off a trigger when the user selects a specific item in a List Box node.

To create a condition using a value from a message:

  1. In the Project select or create a node with a trigger to which you want to add a condition and in the Node Components for the trigger click Trigger Settings. See Adding a trigger.
    The Trigger Settings Editor opens.
    For example, create a Grid List Box 2D node with a List Box: Item Selected trigger and in the Node Components click Trigger Settings for that trigger. See Using the Grid List Box nodes.

  2. In the Trigger Settings Editor click Add condition.
    The Trigger Condition Editor opens.

  3. In the Trigger Condition Editor set the condition that must be met for the trigger to set off. You create a condition by comparing a value you define in the Value A section to the value you define in the Value B section using an operator you set with the Operator property.
    In the Trigger Condition Editor set:Click Save.
    In this example you created a condition which sets off a trigger when the user selects the first item in the Grid List Box 2D node.

Removing a trigger

To remove a trigger, in the Node Components > Triggers section right-click the trigger you want to remove and select Remove.

Using triggers in the API

For details, see the Trigger class in the API reference.

See also

Triggers

Handling user input

Using input manipulators

Using messages

Triggers reference

Actions reference

Keyboard input codes reference

Using scripts